<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
    "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />
<meta name="generator" content="AsciiDoc 8.6.3" />
<title>Gerrit Code Review - Plugin Development</title>
<style type="text/css">
/* Sans-serif font. */
h1, h2, h3, h4, h5, h6,
div.title, caption.title,
thead, p.table.header,
div#toctitle,
span#author, span#revnumber, span#revdate, span#revremark,
div#footer {
  font-family: Arial,Helvetica,sans-serif;
}

/* Serif font. */
div.sectionbody {
  font-family: Georgia,"Times New Roman",Times,serif;
}

/* Monospace font. */
tt {
  font-size: inherit;
}

body {
  margin: 1em 5% 1em 5%;
}

a {
  color: blue;
  text-decoration: underline;
}
a:visited {
  color: fuchsia;
}

em {
  font-style: italic;
  color: navy;
}

strong {
  font-weight: bold;
  color: #083194;
}

tt {
  font-size: inherit;
  color: navy;
}

h1, h2, h3, h4, h5, h6 {
  color: #527bbd;
  margin-top: 1.2em;
  margin-bottom: 0.5em;
  line-height: 1.3;
}

h1, h2, h3 {
  border-bottom: 2px solid silver;
}
h2 {
  padding-top: 0.5em;
}
h3 {
  float: left;
}
h3 + * {
  clear: left;
}

div.sectionbody {
  margin-left: 0;
}

hr {
  border: 1px solid silver;
}

p {
  margin-top: 0.5em;
  margin-bottom: 0.5em;
}

ul, ol, li > p {
  margin-top: 0;
}
ul > li     { color: #aaa; }
ul > li > * { color: black; }

pre {
  padding: 0;
  margin: 0;
}

span#author {
  color: #527bbd;
  font-weight: bold;
  font-size: 1.1em;
}
span#email {
}
span#revnumber, span#revdate, span#revremark {
}

div#footer {
  font-size: small;
  border-top: 2px solid silver;
  padding-top: 0.5em;
  margin-top: 4.0em;
}
div#footer-text {
  float: left;
  padding-bottom: 0.5em;
}
div#footer-badges {
  float: right;
  padding-bottom: 0.5em;
}

div#preamble {
  margin-top: 1.5em;
  margin-bottom: 1.5em;
}
div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
div.admonitionblock {
  margin-top: 1.0em;
  margin-bottom: 1.5em;
}
div.admonitionblock {
  margin-top: 2.0em;
  margin-bottom: 2.0em;
  margin-right: 10%;
  color: #606060;
}

div.content { /* Block element content. */
  padding: 0;
}

/* Block element titles. */
div.title, caption.title {
  color: #527bbd;
  font-weight: bold;
  text-align: left;
  margin-top: 1.0em;
  margin-bottom: 0.5em;
}
div.title + * {
  margin-top: 0;
}

td div.title:first-child {
  margin-top: 0.0em;
}
div.content div.title:first-child {
  margin-top: 0.0em;
}
div.content + div.title {
  margin-top: 0.0em;
}

div.sidebarblock > div.content {
  background: #ffffee;
  border: 1px solid #dddddd;
  border-left: 4px solid #f0f0f0;
  padding: 0.5em;
}

div.listingblock > div.content {
  border: 1px solid #dddddd;
  border-left: 5px solid #f0f0f0;
  background: #f8f8f8;
  padding: 0.5em;
}

div.quoteblock, div.verseblock {
  padding-left: 1.0em;
  margin-left: 1.0em;
  margin-right: 10%;
  border-left: 5px solid #f0f0f0;
  color: #777777;
}

div.quoteblock > div.attribution {
  padding-top: 0.5em;
  text-align: right;
}

div.verseblock > pre.content {
  font-family: inherit;
  font-size: inherit;
}
div.verseblock > div.attribution {
  padding-top: 0.75em;
  text-align: left;
}
/* DEPRECATED: Pre version 8.2.7 verse style literal block. */
div.verseblock + div.attribution {
  text-align: left;
}

div.admonitionblock .icon {
  vertical-align: top;
  font-size: 1.1em;
  font-weight: bold;
  text-decoration: underline;
  color: #527bbd;
  padding-right: 0.5em;
}
div.admonitionblock td.content {
  padding-left: 0.5em;
  border-left: 3px solid #dddddd;
}

div.exampleblock > div.content {
  border-left: 3px solid #dddddd;
  padding-left: 0.5em;
}

div.imageblock div.content { padding-left: 0; }
span.image img { border-style: none; }
a.image:visited { color: white; }

dl {
  margin-top: 0.8em;
  margin-bottom: 0.8em;
}
dt {
  margin-top: 0.5em;
  margin-bottom: 0;
  font-style: normal;
  color: navy;
}
dd > *:first-child {
  margin-top: 0.1em;
}

ul, ol {
    list-style-position: outside;
}
ol.arabic {
  list-style-type: decimal;
}
ol.loweralpha {
  list-style-type: lower-alpha;
}
ol.upperalpha {
  list-style-type: upper-alpha;
}
ol.lowerroman {
  list-style-type: lower-roman;
}
ol.upperroman {
  list-style-type: upper-roman;
}

div.compact ul, div.compact ol,
div.compact p, div.compact p,
div.compact div, div.compact div {
  margin-top: 0.1em;
  margin-bottom: 0.1em;
}

div.tableblock > table {
  border: 3px solid #527bbd;
}
thead, p.table.header {
  font-weight: bold;
  color: #527bbd;
}
tfoot {
  font-weight: bold;
}
td > div.verse {
  white-space: pre;
}
p.table {
  margin-top: 0;
}
/* Because the table frame attribute is overriden by CSS in most browsers. */
div.tableblock > table[frame="void"] {
  border-style: none;
}
div.tableblock > table[frame="hsides"] {
  border-left-style: none;
  border-right-style: none;
}
div.tableblock > table[frame="vsides"] {
  border-top-style: none;
  border-bottom-style: none;
}


div.hdlist {
  margin-top: 0.8em;
  margin-bottom: 0.8em;
}
div.hdlist tr {
  padding-bottom: 15px;
}
dt.hdlist1.strong, td.hdlist1.strong {
  font-weight: bold;
}
td.hdlist1 {
  vertical-align: top;
  font-style: normal;
  padding-right: 0.8em;
  color: navy;
}
td.hdlist2 {
  vertical-align: top;
}
div.hdlist.compact tr {
  margin: 0;
  padding-bottom: 0;
}

.comment {
  background: yellow;
}

.footnote, .footnoteref {
  font-size: 0.8em;
}

span.footnote, span.footnoteref {
  vertical-align: super;
}

#footnotes {
  margin: 20px 0 20px 0;
  padding: 7px 0 0 0;
}

#footnotes div.footnote {
  margin: 0 0 5px 0;
}

#footnotes hr {
  border: none;
  border-top: 1px solid silver;
  height: 1px;
  text-align: left;
  margin-left: 0;
  width: 20%;
  min-width: 100px;
}

div.colist td {
  padding-right: 0.5em;
  padding-bottom: 0.3em;
  vertical-align: top;
}
div.colist td img {
  margin-top: 0.3em;
}

@media print {
  div#footer-badges { display: none; }
}

div#toc {
  margin-bottom: 2.5em;
}

div#toctitle {
  color: #527bbd;
  font-size: 1.1em;
  font-weight: bold;
  margin-top: 1.0em;
  margin-bottom: 0.1em;
}

div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
  margin-top: 0;
  margin-bottom: 0;
}
div.toclevel2 {
  margin-left: 2em;
  font-size: 0.9em;
}
div.toclevel3 {
  margin-left: 4em;
  font-size: 0.9em;
}
div.toclevel4 {
  margin-left: 6em;
  font-size: 0.9em;
}

</style>
<script type="text/javascript">
/*<![CDATA[*/
window.onload = function(){asciidoc.footnotes(); asciidoc.toc(2);}
var asciidoc = {  // Namespace.

/////////////////////////////////////////////////////////////////////
// Table Of Contents generator
/////////////////////////////////////////////////////////////////////

/* Author: Mihai Bazon, September 2002
 * http://students.infoiasi.ro/~mishoo
 *
 * Table Of Content generator
 * Version: 0.4
 *
 * Feel free to use this script under the terms of the GNU General Public
 * License, as long as you do not remove or alter this notice.
 */

 /* modified by Troy D. Hanson, September 2006. License: GPL */
 /* modified by Stuart Rackham, 2006, 2009. License: GPL */

// toclevels = 1..4.
toc: function (toclevels) {

  function getText(el) {
    var text = "";
    for (var i = el.firstChild; i != null; i = i.nextSibling) {
      if (i.nodeType == 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.
        text += i.data;
      else if (i.firstChild != null)
        text += getText(i);
    }
    return text;
  }

  function TocEntry(el, text, toclevel) {
    this.element = el;
    this.text = text;
    this.toclevel = toclevel;
  }

  function tocEntries(el, toclevels) {
    var result = new Array;
    var re = new RegExp('[hH]([2-'+(toclevels+1)+'])');
    // Function that scans the DOM tree for header elements (the DOM2
    // nodeIterator API would be a better technique but not supported by all
    // browsers).
    var iterate = function (el) {
      for (var i = el.firstChild; i != null; i = i.nextSibling) {
        if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
          var mo = re.exec(i.tagName);
          if (mo && (i.getAttribute("class") || i.getAttribute("className")) != "float") {
            result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
          }
          iterate(i);
        }
      }
    }
    iterate(el);
    return result;
  }

  var toc = document.getElementById("toc");
  var entries = tocEntries(document.getElementById("content"), toclevels);
  for (var i = 0; i < entries.length; ++i) {
    var entry = entries[i];
    if (entry.element.id == "")
      entry.element.id = "_toc_" + i;
    var a = document.createElement("a");
    a.href = "#" + entry.element.id;
    a.appendChild(document.createTextNode(entry.text));
    var div = document.createElement("div");
    div.appendChild(a);
    div.className = "toclevel" + entry.toclevel;
    toc.appendChild(div);
  }
  if (entries.length == 0)
    toc.parentNode.removeChild(toc);
},


/////////////////////////////////////////////////////////////////////
// Footnotes generator
/////////////////////////////////////////////////////////////////////

/* Based on footnote generation code from:
 * http://www.brandspankingnew.net/archive/2005/07/format_footnote.html
 */

footnotes: function () {
  var cont = document.getElementById("content");
  var noteholder = document.getElementById("footnotes");
  var spans = cont.getElementsByTagName("span");
  var refs = {};
  var n = 0;
  for (i=0; i<spans.length; i++) {
    if (spans[i].className == "footnote") {
      n++;
      // Use [\s\S] in place of . so multi-line matches work.
      // Because JavaScript has no s (dotall) regex flag.
      note = spans[i].innerHTML.match(/\s*\[([\s\S]*)]\s*/)[1];
      noteholder.innerHTML +=
        "<div class='footnote' id='_footnote_" + n + "'>" +
        "<a href='#_footnoteref_" + n + "' title='Return to text'>" +
        n + "</a>. " + note + "</div>";
      spans[i].innerHTML =
        "[<a id='_footnoteref_" + n + "' href='#_footnote_" + n +
        "' title='View footnote' class='footnote'>" + n + "</a>]";
      var id =spans[i].getAttribute("id");
      if (id != null) refs["#"+id] = n;
    }
  }
  if (n == 0)
    noteholder.parentNode.removeChild(noteholder);
  else {
    // Process footnoterefs.
    for (i=0; i<spans.length; i++) {
      if (spans[i].className == "footnoteref") {
        var href = spans[i].getElementsByTagName("a")[0].getAttribute("href");
        href = href.match(/#.*/)[0];  // Because IE return full URL.
        n = refs[href];
        spans[i].innerHTML =
          "[<a href='#_footnote_" + n +
          "' title='View footnote' class='footnote'>" + n + "</a>]";
      }
    }
  }
}

}
/*]]>*/
</script>
</head>
<body class="article">
<div id="header">
<h1>Gerrit Code Review - Plugin Development</h1>
<span id="revnumber">version 2.5</span>
<div id="toc">
  <div id="toctitle">Table of Contents</div>
  <noscript><p><b>JavaScript must be enabled in your browser to display the table of contents.</b></p></noscript>
</div>
</div>
<div id="content">
<div id="preamble">
<div class="sectionbody">
<div class="paragraph"><p>The Gerrit server functionality can be extended by installing plugins.
This page describes how plugins for Gerrit can be developed.</p></div>
<div class="paragraph"><p>Depending on how tightly the extension code is coupled with the Gerrit
server code, there is a distinction between <tt>plugins</tt> and <tt>extensions</tt>.</p></div>
<div class="paragraph" id="plugin"><p>A <tt>plugin</tt> in Gerrit is tightly coupled code that runs in the same
JVM as Gerrit. It has full access to all server internals. Plugins
are tightly coupled to a specific major.minor server version and
may require source code changes to compile against a different
server version.</p></div>
<div class="paragraph" id="extension"><p>An <tt>extension</tt> in Gerrit runs inside of the same JVM as Gerrit
in the same way as a plugin, but has limited visibility to the
server&#8217;s internals. The limited visibility reduces the extension&#8217;s
dependencies, enabling it to be compatible across a wider range
of server versions.</p></div>
<div class="paragraph"><p>Most of this documentation refers to either type as a plugin.</p></div>
</div>
</div>
<div class="sect1">
<h2 id="getting-started">Getting started</h2>
<div class="sectionbody">
<div class="paragraph"><p>To get started with the development of a plugin there are two
recommended ways:</p></div>
<div class="olist arabic"><ol class="arabic">
<li>
<p>
use the Gerrit Plugin Maven archetype to create a new plugin project:
</p>
<div class="paragraph"><p>With the Gerrit Plugin Maven archetype you can create a skeleton for a
plugin project.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>mvn archetype:generate -DarchetypeGroupId=com.google.gerrit \
    -DarchetypeArtifactId=gerrit-plugin-archetype \
    -DarchetypeVersion=2.5-SNAPSHOT \
    -DgroupId=com.google.gerrit \
    -DartifactId=testPlugin</tt></pre>
</div></div>
<div class="paragraph"><p>Maven will ask for additional properties and then create the plugin in
the current directory. To change the default property values answer <em>n</em>
when Maven asks to confirm the properties configuration. It will then
ask again for all properties including those with predefined default
values.</p></div>
</li>
<li>
<p>
clone the sample helloworld plugin:
</p>
<div class="paragraph"><p>This is a Maven project that adds an SSH command to Gerrit to print
out a hello world message. It can be taken as an example to develop
an own plugin.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>$ git clone https://gerrit.googlesource.com/plugins/helloworld</tt></pre>
</div></div>
<div class="paragraph"><p>When starting from this example one should take care to adapt the
<tt>Gerrit-ApiVersion</tt> in the <tt>pom.xml</tt> to the version of Gerrit for which
the plugin is developed. If the plugin is developed for a released
Gerrit version (no <tt>SNAPSHOT</tt> version) then the URL for the
<tt>gerrit-api-repository</tt> in the <tt>pom.xml</tt> needs to be changed to
<tt>https://gerrit-api.commondatastorage.googleapis.com/release/</tt>.</p></div>
</li>
</ol></div>
</div>
</div>
<div class="sect1">
<h2 id="API">API</h2>
<div class="sectionbody">
<div class="paragraph"><p>There are two different API formats offered against which plugins can
be developed:</p></div>
<div class="dlist"><dl>
<dt class="hdlist1">
gerrit-extension-api.jar
</dt>
<dd>
<p>
  A stable but thin interface. Suitable for extensions that need
  to be notified of events, but do not require tight coupling to
  the internals of Gerrit. Extensions built against this API can
  expect to be binary compatible across a wide range of server
  versions.
</p>
</dd>
<dt class="hdlist1">
gerrit-plugin-api.jar
</dt>
<dd>
<p>
  The complete internals of the Gerrit server, permitting a
  plugin to tightly couple itself and provide additional
  functionality that is not possible as an extension. Plugins
  built against this API are expected to break at the source
  code level between every major.minor Gerrit release. A plugin
  that compiles against 2.5 will probably need source code level
  changes to work with 2.6, 2.7, and so on.
</p>
</dd>
</dl></div>
</div>
</div>
<div class="sect1">
<h2 id="_manifest">Manifest</h2>
<div class="sectionbody">
<div class="paragraph"><p>Plugins may provide optional description information with standard
manifest fields:</p></div>
<div class="exampleblock">
<div class="content">
<div class="literalblock">
<div class="content">
<pre><tt>Implementation-Title: Example plugin showing examples
Implementation-Version: 1.0
Implementation-Vendor: Example, Inc.
Implementation-URL: http://example.com/opensource/plugin-foo/</tt></pre>
</div></div>
</div></div>
<div class="sect2">
<h3 id="_apitype">ApiType</h3>
<div class="paragraph"><p>Plugins using the tightly coupled <tt>gerrit-plugin-api.jar</tt> must
declare this API dependency in the manifest to gain access to server
internals. If no <tt>Gerrit-ApiType</tt> is specified the stable <tt>extension</tt>
API will be assumed. This may cause ClassNotFoundExceptions when
loading a plugin that needs the plugin API.</p></div>
<div class="exampleblock">
<div class="content">
<div class="literalblock">
<div class="content">
<pre><tt>Gerrit-ApiType: plugin</tt></pre>
</div></div>
</div></div>
</div>
<div class="sect2">
<h3 id="_explicit_registration">Explicit Registration</h3>
<div class="paragraph"><p>Plugins that use explicit Guice registration must name the Guice
modules in the manifest. Up to three modules can be named in the
manifest. <tt>Gerrit-Module</tt> supplies bindings to the core server;
<tt>Gerrit-SshModule</tt> supplies SSH commands to the SSH server (if
enabled); <tt>Gerrit-HttpModule</tt> supplies servlets and filters to the HTTP
server (if enabled). If no modules are named automatic registration
will be performed by scanning all classes in the plugin JAR for
<tt>@Listen</tt> and <tt>@Export("")</tt> annotations.</p></div>
<div class="exampleblock">
<div class="content">
<div class="literalblock">
<div class="content">
<pre><tt>Gerrit-Module:     tld.example.project.CoreModuleClassName
Gerrit-SshModule:  tld.example.project.SshModuleClassName
Gerrit-HttpModule: tld.example.project.HttpModuleClassName</tt></pre>
</div></div>
</div></div>
</div>
<div class="sect2">
<h3 id="reload_method">Reload Method</h3>
<div class="paragraph"><p>If a plugin holds an exclusive resource that must be released before
loading the plugin again (for example listening on a network port or
acquiring a file lock) the manifest must declare <tt>Gerrit-ReloadMode</tt>
to be <tt>restart</tt>. Otherwise the preferred method of <tt>reload</tt> will
be used, as it enables the server to hot-patch an updated plugin
with no down time.</p></div>
<div class="exampleblock">
<div class="content">
<div class="literalblock">
<div class="content">
<pre><tt>Gerrit-ReloadMode: restart</tt></pre>
</div></div>
</div></div>
<div class="paragraph"><p>In either mode (<em>restart</em> or <em>reload</em>) any plugin or extension can
be updated without restarting the Gerrit server. The difference is
how Gerrit handles the upgrade:</p></div>
<div class="dlist"><dl>
<dt class="hdlist1">
restart
</dt>
<dd>
<p>
  The old plugin is completely stopped. All registrations of SSH
  commands and HTTP servlets are removed. All registrations of any
  extension points are removed. All registered LifecycleListeners
  have their <tt>stop()</tt> method invoked in reverse order. The new
  plugin is started, and registrations are made from the new
  plugin. There is a brief window where neither the old nor the
  new plugin is connected to the server. This means SSH commands
  and HTTP servlets will return not found errors, and the plugin
  will not be notified of events that occurred during the restart.
</p>
</dd>
<dt class="hdlist1">
reload
</dt>
<dd>
<p>
  The new plugin is started. Its LifecycleListeners are permitted
  to perform their <tt>start()</tt> methods. All SSH and HTTP registrations
  are atomically swapped out from the old plugin to the new plugin,
  ensuring the server never returns a not found error. All extension
  point listeners are atomically swapped out from the old plugin to
  the new plugin, ensuring no events are missed (however some events
  may still route to the old plugin if the swap wasn&#8217;t complete yet).
  The old plugin is stopped.
</p>
</dd>
</dl></div>
<div class="paragraph"><p>To reload/restart a plugin the <a href="cmd-plugin-reload.html">plugin reload</a>
command can be used.</p></div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="classpath">Classpath</h2>
<div class="sectionbody">
<div class="paragraph"><p>Each plugin is loaded into its own ClassLoader, isolating plugins
from each other. A plugin or extension inherits the Java runtime
and the Gerrit API chosen by <tt>Gerrit-ApiType</tt> (extension or plugin)
from the hosting server.</p></div>
<div class="paragraph"><p>Plugins are loaded from a single JAR file. If a plugin needs
additional libraries, it must include those dependencies within
its own JAR. Plugins built using Maven may be able to use the
<a href="http://maven.apache.org/plugins/maven-shade-plugin/">shade plugin</a>
to package additional dependencies. Relocating (or renaming) classes
should not be necessary due to the ClassLoader isolation.</p></div>
</div>
</div>
<div class="sect1">
<h2 id="ssh">SSH Commands</h2>
<div class="sectionbody">
<div class="paragraph"><p>Plugins may provide commands that can be accessed through the SSH
interface (extensions do not have this option).</p></div>
<div class="paragraph"><p>Command implementations must extend the base class SshCommand:</p></div>
<div class="exampleblock">
<div class="content">
<div class="literalblock">
<div class="content">
<pre><tt>import com.google.gerrit.sshd.SshCommand;</tt></pre>
</div></div>
<div class="literalblock">
<div class="content">
<pre><tt>class PrintHello extends SshCommand {
  protected abstract void run() {
    stdout.print("Hello\n");
  }
}</tt></pre>
</div></div>
</div></div>
<div class="paragraph"><p>If no Guice modules are declared in the manifest, SSH commands may
use auto-registration by providing an <tt>@Export</tt> annotation:</p></div>
<div class="exampleblock">
<div class="content">
<div class="literalblock">
<div class="content">
<pre><tt>import com.google.gerrit.extensions.annotations.Export;
import com.google.gerrit.sshd.SshCommand;</tt></pre>
</div></div>
<div class="literalblock">
<div class="content">
<pre><tt>@Export("print")
class PrintHello extends SshCommand {
  protected abstract void run() {
    stdout.print("Hello\n");
  }
}</tt></pre>
</div></div>
</div></div>
<div class="paragraph"><p>If explicit registration is being used, a Guice module must be
supplied to register the SSH command and declared in the manifest
with the <tt>Gerrit-SshModule</tt> attribute:</p></div>
<div class="exampleblock">
<div class="content">
<div class="literalblock">
<div class="content">
<pre><tt>import com.google.gerrit.sshd.PluginCommandModule;</tt></pre>
</div></div>
<div class="literalblock">
<div class="content">
<pre><tt>class MyCommands extends PluginCommandModule {
  protected void configureCommands() {
    command("print").to(PrintHello.class);
  }
}</tt></pre>
</div></div>
</div></div>
<div class="paragraph"><p>For a plugin installed as name <tt>helloworld</tt>, the command implemented
by PrintHello class will be available to users as:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>$ ssh -p 29418 review.example.com helloworld print</tt></pre>
</div></div>
</div>
</div>
<div class="sect1">
<h2 id="http">HTTP Servlets</h2>
<div class="sectionbody">
<div class="paragraph"><p>Plugins or extensions may register additional HTTP servlets, and
wrap them with HTTP filters.</p></div>
<div class="paragraph"><p>Servlets may use auto-registration to declare the URL they handle:</p></div>
<div class="exampleblock">
<div class="content">
<div class="literalblock">
<div class="content">
<pre><tt>import com.google.gerrit.extensions.annotations.Export;
import com.google.inject.Singleton;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;</tt></pre>
</div></div>
<div class="literalblock">
<div class="content">
<pre><tt>@Export("/print")
@Singleton
class HelloServlet extends HttpServlet {
  protected void doGet(HttpServletRequest req, HttpServletResponse res) throws IOException {
    res.setContentType("text/plain");
    res.setCharacterEncoding("UTF-8");
    res.getWriter().write("Hello");
  }
}</tt></pre>
</div></div>
</div></div>
<div class="paragraph"><p>The auto registration only works for standard servlet mappings like
<tt>/foo</tt> or <tt>/foo/*</tt>. Regex style bindings must use a Guice ServletModule
to register the HTTP servlets and declare it explicitly in the manifest
with the <tt>Gerrit-HttpModule</tt> attribute:</p></div>
<div class="exampleblock">
<div class="content">
<div class="literalblock">
<div class="content">
<pre><tt>import com.google.inject.servlet.ServletModule;</tt></pre>
</div></div>
<div class="literalblock">
<div class="content">
<pre><tt>class MyWebUrls extends ServletModule {
  protected void configureServlets() {
    serve("/print").with(HelloServlet.class);
  }
}</tt></pre>
</div></div>
</div></div>
<div class="paragraph"><p>For a plugin installed as name <tt>helloworld</tt>, the servlet implemented
by HelloServlet class will be available to users as:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>$ curl http://review.example.com/plugins/helloworld/print</tt></pre>
</div></div>
</div>
</div>
<div class="sect1">
<h2 id="data-directory">Data Directory</h2>
<div class="sectionbody">
<div class="paragraph"><p>Plugins can request a data directory with a <tt>@PluginData</tt> File
dependency. A data directory will be created automatically by the
server in <tt>$site_path/data/$plugin_name</tt> and passed to the plugin.</p></div>
<div class="paragraph"><p>Plugins can use this to store any data they want.</p></div>
<div class="exampleblock">
<div class="content">
<div class="literalblock">
<div class="content">
<pre><tt>@Inject
MyType(@PluginData java.io.File myDir) {
  new FileInputStream(new File(myDir, "my.config"));
}</tt></pre>
</div></div>
</div></div>
</div>
</div>
<div class="sect1">
<h2 id="documentation">Documentation</h2>
<div class="sectionbody">
<div class="paragraph"><p>If a plugin does not register a filter or servlet to handle URLs
<tt>/Documentation/*</tt> or <tt>/static/*</tt>, the core Gerrit server will
automatically export these resources over HTTP from the plugin JAR.</p></div>
<div class="paragraph"><p>Static resources under <tt>static/</tt> directory in the JAR will be
available as <tt>/plugins/helloworld/static/resource</tt>.</p></div>
<div class="paragraph"><p>Documentation files under <tt>Documentation/</tt> directory in the JAR
will be available as <tt>/plugins/helloworld/Documentation/resource</tt>.</p></div>
<div class="paragraph"><p>Documentation may be written in
<a href="http://daringfireball.net/projects/markdown/">Markdown</a> style
if the file name ends with <tt>.md</tt>. Gerrit will automatically convert
Markdown to HTML if accessed with extension <tt>.html</tt>.</p></div>
<div class="paragraph" id="macros"><p>Within the Markdown documentation files macros can be used that allow
to write documentation with reasonably accurate examples that adjust
automatically based on the installation.</p></div>
<div class="paragraph"><p>The following macros are supported:</p></div>
<div class="tableblock">
<table rules="all"
width="40%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<thead>
<tr>
<th align="left" valign="top">Macro       </th>
<th align="left" valign="top"> Replacement</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left" valign="top"><p class="table">@PLUGIN@</p></td>
<td align="left" valign="top"><p class="table">name of the plugin</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">@URL@</p></td>
<td align="left" valign="top"><p class="table">Gerrit Web URL</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">@SSH_HOST@</p></td>
<td align="left" valign="top"><p class="table">SSH Host</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">@SSH_PORT@</p></td>
<td align="left" valign="top"><p class="table">SSH Port</p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>The macros will be replaced when the documentation files are rendered
from Markdown to HTML.</p></div>
<div class="paragraph"><p>Macros that start with <tt>\</tt> such as <tt>\@KEEP@</tt> will render as <tt>@KEEP@</tt>
even if there is an expansion for <tt>KEEP</tt> in the future.</p></div>
<div class="sect2">
<h3 id="auto-index">Automatic Index</h3>
<div class="paragraph"><p>If a plugin does not handle its <tt>/</tt> URL itself, Gerrit will
redirect clients to the plugin&#8217;s <tt>/Documentation/index.html</tt>.
Requests for <tt>/Documentation/</tt> (bare directory) will also redirect
to <tt>/Documentation/index.html</tt>.</p></div>
<div class="paragraph"><p>If neither resource <tt>Documentation/index.html</tt> or
<tt>Documentation/index.md</tt> exists in the plugin JAR, Gerrit will
automatically generate an index page for the plugin&#8217;s documentation
tree by scanning every <tt>*.md</tt> and <tt>*.html</tt> file in the Documentation/
directory.</p></div>
<div class="paragraph"><p>For any discovered Markdown (<tt>*.md</tt>) file, Gerrit will parse the
header of the file and extract the first level one title. This
title text will be used as display text for a link to the HTML
version of the page.</p></div>
<div class="paragraph"><p>For any discovered HTML (<tt>*.html</tt>) file, Gerrit will use the name
of the file, minus the <tt>*.html</tt> extension, as the link text. Any
hyphens in the file name will be replaced with spaces.</p></div>
<div class="paragraph"><p>If a discovered file name beings with <tt>cmd-</tt> it will be clustered
into a <em>Commands</em> section of the generated index page. All other
files are clustered under a <em>Documentation</em> section.</p></div>
<div class="paragraph"><p>Some optional information from the manifest is extracted and
displayed as part of the index page, if present in the manifest:</p></div>
<div class="tableblock">
<table rules="all"
width="40%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<thead>
<tr>
<th align="left" valign="top">Field       </th>
<th align="left" valign="top"> Source Attribute</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left" valign="top"><p class="table">Name</p></td>
<td align="left" valign="top"><p class="table">Implementation-Title</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">Vendor</p></td>
<td align="left" valign="top"><p class="table">Implementation-Vendor</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">Version</p></td>
<td align="left" valign="top"><p class="table">Implementation-Version</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">URL</p></td>
<td align="left" valign="top"><p class="table">Implementation-URL</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">API Version</p></td>
<td align="left" valign="top"><p class="table">Gerrit-ApiVersion</p></td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="deployment">Deployment</h2>
<div class="sectionbody">
<div class="paragraph"><p>Compiled plugins and extensions can be deployed to a running Gerrit
server using the <a href="cmd-plugin-install.html">plugin install</a> command.</p></div>
<div class="paragraph"><p>Plugins can also be copied directly into the server&#8217;s
directory at <tt>$site_path/plugins/$name.jar</tt>.  The name of
the JAR file, minus the <tt>.jar</tt> extension, will be used as the
plugin name. Unless disabled, servers periodically scan this
directory for updated plugins. The time can be adjusted by
<a href="config-gerrit.html#plugins.checkFrequency">plugins.checkFrequency</a>.</p></div>
<div class="paragraph"><p>For disabling plugins the <a href="cmd-plugin-remove.html">plugin remove</a>
command can be used.</p></div>
<div class="paragraph"><p>Disabled plugins can be re-enabled using the
<a href="cmd-plugin-enable.html">plugin enable</a> command.</p></div>
</div>
</div>
<hr style="
  height: 2px;
  color: silver;
  margin-top: 1.2em;
  margin-bottom: 0.5em;
">
<div class="paragraph"><p>Part of <a href="index.html">Gerrit Code Review</a></p></div>
</div>
<div id="footnotes"><hr /></div>
<div id="footer">
<div id="footer-text">
Version 2.5<br />
Last updated 2012-10-31 19:34:02 CET
</div>
</div>
</body>
</html>
